<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
 <HEAD>
  <TITLE>Apache module mod_example</TITLE>
 </HEAD>
 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
 <BODY
  BGCOLOR="#FFFFFF"
  TEXT="#000000"
  LINK="#0000FF"
  VLINK="#000080"
  ALINK="#FF0000"
 >
  <!--#include virtual="header.html" -->
  <H1 ALIGN="CENTER">Module mod_example</h1>
  <P>
  This module is contained in the <CODE>modules/mod_example.c</CODE> file, and
  <STRONG>is not</STRONG> compiled in by default.  It illustrates many of
  the aspects of the
  <A
   HREF="../misc/API.html"
   REL="Help"
  >Apache 1.2 API</A>
  and, when used, demonstrates the manner in which module callbacks are
  triggered by the server.
  </P>
  <H2>Summary</H2>
  <P>
  The files in the <CODE>src/modules/example directory</CODE> under the
  Apache distribution directory tree are provided as an example to those
  that wish to write modules that use the Apache API.
  </P>
  <P>
  The main file is <CODE>mod_example.c</CODE>, which illustrates all
  the different callback mechanisms and call syntaces.  By no means does
  an add-on module need to include routines for all of the callbacks -
  quite the contrary!
  </P>
  <P>
  The example module is an actual working module.  If you link it into
  your server, enable the "example-handler" handler for a location, and
  then browse to that location, you will see a display of
  some of the tracing the example module did as the various callbacks
  were made.
  </P>
  <P>
  To include the example module in your server, follow the steps below:
  </P>
  <OL>
   <LI>Uncomment the "Module example_module" line near the bottom of
    the <CODE>src/Configuration</CODE> file.  If there isn't one, add
    it; it should look like this:
    <PRE>
     Module example_module        modules/example/mod_example.o
    </PRE>
   </LI>
   <LI>Run the <CODE>src/Configure</CODE> script
    ("<SAMP>cd&nbsp;src;&nbsp;./Configure</SAMP>").  This will
    build the Makefile for the server itself, and update the
    <CODE>src/modules/Makefile</CODE> for any additional modules you
    have requested from beneath that subdirectory.
   </LI>
   <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE>
    directory).
   </LI>
  </OL>
  <P>
  To add another module of your own:
  </P>
  <OL TYPE="A">
   <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP>
   </LI>
   <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP>
   </LI>
   <LI>Modify the files in the new directory.
   </LI>
   <LI>Follow steps [1] through [3] above, with appropriate changes.
   </LI>
  </OL>
  <H3>
   Using the <SAMP>mod_example</SAMP> Module
  </H3>
  <P>
  To activate the example module, include a block similar to the
  following in your <SAMP>srm.conf</SAMP> file:
  </P>
  <PRE>
   &lt;Location /example-info&gt;
       SetHandler example-handler
   &lt;/Location&gt;
  </PRE>
  <P>
  As an alternative, you can put the following into a
  <A
   HREF="core.html#accessfilename"
  ><SAMP>.htaccess</SAMP></A>
  file and then request the file &quot;test.example&quot; from that
  location:
  </P>
  <PRE>
   AddHandler example-handler .example
  </PRE>
  <P>
  After reloading/restarting your server, you should be able to browse
  to this location and see the brief display mentioned earlier.
  </P>
  <H2>Directives</H2>
  <P>
  <UL>
   <LI><A HREF="#example">Example</A>
   </LI>
  </UL>
  </P>
  <HR>
  <H2><A NAME="example">
   Example
  </A></H2>
  <P>
  <STRONG>Syntax:</STRONG> Example
  <BR>
  <STRONG>Default:</STRONG> None
  <BR>
  <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess
  <BR>
  <STRONG>Override:</STRONG> Options
  <BR>
  <STRONG>Status:</STRONG> Extension
  <BR>
  <STRONG>Module:</STRONG> mod_example
  </P>
  <P>
  The Example directive activates the example module's content handler
  for a particular location or file type.  It takes no arguments.  If
  you browse to an URL to which the example content-handler applies, you
  will get a display of the routines within the module and how and in
  what order they were called to service the document request.
  </P>
  <!--#include virtual="footer.html" -->
 </BODY>
</HTML>
